home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 April / macformat-023.iso / Shareware City / Newton / slurpee-13 / SlurpOld.txt < prev   
Encoding:
Text File  |  1993-10-15  |  6.6 KB  |  166 lines  |  [TEXT/R*ch]
  1. Slurp    0.9        by Zz Zimmerman
  2.  
  3. For NTK 1.0b6 (b4 will NOT work).  Slurp is a utility for sending
  4. data to the Newton.  You use your favorite communications application
  5. (i.e. ClarisWorks, MacTerminal) to send a text file to the Newton
  6. over the serial port.  Slurp receives the data, converts each line
  7. into a soup entry, and then stores the result in the soup.  This
  8. version of Slurp only adds records to an existing soup, it does
  9. not create one.  It also assumes that the target soup is a union
  10. soup.
  11.  
  12. The text file tells Slurp everything it needs to know.  Basically,
  13. the name of the soup to store into, the format of the entries in
  14. that soup (slot names, data types), followed by a list of tab
  15. delimited strings to be converted into entries.  Each line is
  16. assumed to be a complete element.  For example:
  17.  
  18.     Names
  19.     {cardType: 0, phones: ["string", "string", "string", "string"], email: "string", company: "string", address: "string", address2: "string", city: "string", region: "string", country: "string", postal_code: "string", bday: "date", name: {class: 'person, honorific: "string", first: "string", last: "string", title: "string"}}
  20.     0    111-1111    222-2222    333-3333    444-4444    email    company1    address    address2    city    region    country    postal_code    4/23/62    person    Mr.    Bob1    ADobbs    Dudeface    
  21.     0    111-1111    222-2222    333-3333    444-4444    email    company2    address    address2    city    region    country    postal_code    4/23/62    person    Mr.    Joe2    ADobbs    Dudeface    
  22.     0    111-1111    222-2222    333-3333    444-4444    email    company3    address    address2    city    region    country    postal_code    4/23/62    person    Mr.    Bif3    ADobbs    Dudeface    
  23.     …
  24.     …
  25.     …
  26.     0    111-1111    222-2222    333-3333    444-4444    email    company3    address    address2    city    region    country    postal_code    4/23/62    person    Mr.    Bif3    ADobbs    Dudeface    
  27.     BYE!
  28.  
  29.  
  30. The first line:
  31.  
  32.     Names
  33.  
  34. is the name of the soup to add the entries to.  In this example, we'll
  35. add some cards to the cardfile's Names soup.
  36.  
  37. The second line:
  38.  
  39.     {cardType: 0, phones: ["string", "string", "string", "string"], email: "string", company: "string", address: "string", address2: "string", city: "string", region: "string", country: "string", postal_code: "string", bday: "date", name: {class: 'person, honorific: "string", first: "string", last: "string", title: "string"}}
  40.  
  41. is a line of NewtonScript that specifies the format of an entry
  42. (ie. entrySpec) for this soup.  The NewtonScript is compiled by 
  43. Slurp, and the resulting frame is used for determining data types.
  44.  
  45. THE PROBLEM:
  46.     Unfortunately, tab-delimited files are just text, with no real
  47.     type specifications.  Because of this, each slot value comes
  48.     in as a string, and must be converted to the appropriate type.
  49.     The type for each slot value comes from the entrySpec.
  50.  
  51. The slot values in the entrySpec are sample values that have the
  52. desired class.  For example, if a slot value was to be converted
  53. to an integer, you could store 0 in the entrySpec.  If the slot
  54. value is to be converted into a symbol, you could store 'symbol
  55. in the entrySpec.  Slurp uses the ClassOf function to determine
  56. the desired class, and then converts the string as needed.
  57.  
  58. PROBLEM #2:    
  59.     Unfortunately, the ClassOf function doesn't always succeed.
  60.     For example, in the case of a date value.  The file has a
  61.     human readable version of the date in a string.  The Names
  62.     soup stores dates as a big integer (the result of the
  63.     StringToDate function).  Storing an integer in the entrySpec
  64.     won't do it.  Slurp needs to know how to convert the string
  65.     into a date.
  66.     
  67. The solution to this problem is less than elegant, but is very
  68. flexible.  When the value in the entrySpec is of type 'string,
  69. the contents of the string are used to specify the type.
  70.  
  71. For example, if the desired type is string, we use the string:
  72.  
  73.     "string"
  74.  
  75. This specifies that the data is to be converted into (or left
  76. as) a simple string.  To specify a different type like 'date,
  77. we use the string:
  78.  
  79. "date"
  80.  
  81. The type conversion routine inside Slurp can be extended to
  82. support whatever types you may come up with.
  83.  
  84. The next lines are tab delimited text that contain the data for the
  85. soup entries.  The data must be specified in the same order as the
  86. sample soup entry.  So in the example, 0 is the cardType, 111-1111 is
  87. the first phone number in the phones array, and so on.  Note
  88. that all the fields are tab-delimited.  There are no braces
  89. or brackets used to specify frames or arrays.
  90.  
  91. In order to make Slurp disconnect automatically, the last line
  92. of the file is:
  93.  
  94. BYE!
  95.  
  96. signalling to Slurp that all the data has been received, and the
  97. connection can now be closed.
  98.  
  99. To use Slurp, simply download it to your Newton.  Open the communications
  100. program on the Macintosh, and open a connection with the following specs:
  101.  
  102.   Serial Tool, 9600 baud, 8 data bits, 1 stop bit, XON/XOFF handshaking
  103.  
  104. You can use the same cable that you use with NTK/Connection.
  105.  
  106. For file transfer, specify the Text Tool.
  107.  
  108. Now you are ready to slurp some soup.  
  109.  
  110. Open Slurp and tap the "Receive..." button.  
  111.  
  112. On the Mac, choose "Send File..." in the comm program, and choose the 
  113. file to be sent.  Slurp will display the number of entries
  114. received in a view near the top of the screen.  When the file transfer
  115. is complete, Slurp will automatically disconnect.
  116.  
  117. As for the implementation, the main routines are in:
  118.  
  119.     protoSerialProtocol    -    InputScripts for receiving data.
  120.     
  121.     nextSlotValue        -    Returns the next piece of data from the
  122.                             tab delimited line of text.
  123.                             
  124.     matchTypes            -    Coerces a string into a specified type.
  125.                             
  126.     buildEntry            -    Recursive routine to convert each string
  127.                             from the data file into the correct type
  128.                             and store the new value in a frame/entry.
  129.                             
  130.     newStatus            -    Displays program information in a static
  131.                             text window on the Newton.
  132.  
  133.     protoVT42            -    This is just a little auto-sizing text
  134.                             view useful for displaying status
  135.                             messages.  It's based on the "Wrap It
  136.                             Up" sample from PIE DTS.
  137.  
  138.     epInit, epConnect,    -    Global functions for instantiating,
  139.     epDisconnect            connecting and disconnecting an I/O
  140.                             endpoint.
  141.                             
  142. Caveats/Bugs:
  143.  
  144. The previous version of this code was pretty ugly, and this is
  145. meant to be a much cleaner and more usable version.  Sorry for
  146. the pre-release.
  147.  
  148. I still have not been able to call the endpoint :Dispose function
  149. without getting errors.  Calling :Abort followed by :Release seems
  150. to be the best.  Maybe endpoints shouldn't be disposed of?  It
  151. doesn't seem to bother the Toolkit App, so maybe :Release is
  152. enough...
  153.  
  154. The views in Slurp are mostly debugging windows that I used while
  155. debugging it.  The "Slurp State:" view is the most useful.  The
  156. "Connection State:" view display the results of the :State()
  157. communications function after certain operations.  Tap the 
  158. "Connection State:" label to see the current state.
  159.  
  160.                             
  161. I hope this helps,
  162.  
  163.  
  164. ...Zz
  165.     
  166.